
/**
 * This class is intended to tokenize a line of object code of the form defined in
 * Appendix C and D of the CSE7000 lab manual.
 * 
 * @author Tobin Chee
 *
 * Change Log:<br>
 * 	- No Changes
 */
public interface ObjectFileTokenizer {
	
	/**
	 * Enumeration of the token types returned by reference as parameter {@link type} for methods
	 * getNextToken() and getNextNonSeparatorToken().
	 * 
	 * @author Tobin Chee
	 * 
	 * Change Log:<br>
	 *	- No Changes
	 */
	enum TokenType{
		/**
		 * This token type denotes a separator token. A separator token is a string comprised of a
		 * single character from the set of legal separator tokens.<br>
		 * The set of legal separator tokens is:<br>
		 * 		{'|')
		 */
		SEPARATOR,
		/**
		 * This token type denotes a text token. A text token is a string comprised of comprised of
		 * one or more characters from the set of legal text tokens.<br>
		 * The set of legal separator tokens is:<br><pre>
		 *      {'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i',
		 * 		 'j', 'k', 'l', 'm', 'n', 'o', 'p', 'q', 'r',
		 * 		 's', 't', 'u', 'v', 'w', 'x', 'y', 'z', 'A',
		 * 		 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J',
		 * 		 'K', 'L', 'M', 'N', 'O', 'P', 'Q', 'R', 'S',
		 * 		 'T', 'U', 'V', 'W', 'X', 'Y', 'Z', '1', '2',
		 * 		 '3', '4', '5', '6', '7', '8', '9', '0', '+',
		 * 		 '-', '*', '/', ':'}</pre>
		 */
		TEXT,
		/**
		 * This token type denotes an error token. An error token is a string comprised of characters not in the set of legal separator and text tokens.
		 */
		ERROR,
		/**
		 * This token type denotes an empty token. An empty token is an empty string.
		 */
		EMPTY;
	}
	
	/**
	 * Gets the next token from sourceLine and passes token and type back by reference.
	 * <p>
	 * - If the incoming sourceLine begins with a separator character, that character is removed from sourceLine
	 * and placed in token, then the method terminates. Accordingly, Tokens of type TokenType.SEPARATOR
	 * are limited to one character in length.<br>
	 * - If the incoming sourceLine is empty, token is set to an empty string and type is set to TokenType.EMPTY.<br>
	 * - Otherwise, this method will continuously remove characters from
	 * sourceLine and append them to token until a separator character or the end of sourceLine is encountered. The
	 * terminating separator is preserved within sourceLine, and accordingly is not included in token. If the outgoing
	 * token only contains characters in the set of legal text characters (see {@link ObjectFileTokenizer.TokenType}
	 * for a definition), then type is set to TokenType.TEXT. Otherwise, type is set to TokenType.ERROR<br><br>
	 * 
	 * See {@link ObjectFileTokenizer.TokenType} for a description of the token types and legal character sets.
	 * 
	 * @param sourceLine Line of text from which the next token is taken.
	 * @param token String token pulled from sourceLine.
	 * @param type Token type of outgoing token.
	 * @author Tobin Chee
	 * 
	 * Change Log:<br>
	 * 	- No Changes.
	 */
	void getNextToken(StringBuffer sourceLine, StringBuffer token, ObjectFileTokenizer.TokenType[] type);
	
	/**
	 * Gets the next non-separator token from sourceLine and passes token and the type back by reference.
	 * <p>
	 * - If the incoming sourceLine contains leading separators, they will all be removed. After all leading separators
	 * have been removed from sourceLine, this method calls {@link ObjectFileTokenizer#getNextToken} on the remaining
	 * sourceLine.<br>
	 * - If the incoming sourceLine contains only separators or is an empty string,  token is set to an empty string
	 * and type is set to TokenType.EMPTY.<br><br>
	 * 
	 * See {@link ObjectFileTokenizer.TokenType} for a better description of the token types.
	 * 
	 * 
	 * @param sourceLine Line of text from which the next token is taken.
	 * @param token String token pulled from sourceLine.
	 * @param type Token type of outgoing token.
	 * @author Tobin Chee
	 * 
	 * Change Log:<br>
	 * 	- No Changes.
	 */
	void getNextNonSeparatorToken(StringBuffer sourceLine, StringBuffer token, ObjectFileTokenizer.TokenType[] type);
}
